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USER'S GUIDE FOR SUBROUTINE PL0T3D 

Identification 

PL0T3D - A Subroutine T^ich Generates Three Dimensional Hidden Line Displays 

Author - Larry Gales 

Date - April 1978, Center for Quantitative Science in Forestry, Fisheries, 

and Wildlife, University of Washington, Seattle, Washington 98195 

Purpose 

PL0T3D is a subroutine package which generates a variety of three dimensional 

hiddvsn line CalComp-type displays. The package features multiple plots per page, 

with or without annotation, or annotation without plots; multiple pages; automatic 

scaling; flexible titling; two dimensional interpolation over the image space; 

choice of size and location of plots on a page; choice of viewing angle and viewing 

distance; and various options which affect the appearance of the plot. Each page of 

plots fits on a standard 8-1/2 x 11 inch page with margins of sufficient size to 

permit inclusion in three ring binders. 

PL0T3D is built around an NX by NY grid of cells called an image space. The 

# 

image space is filled with numeric values from a binary file of x,y,z coordinates 
which contains data points as follows: 

x^, y^, z^ 
• 

X , y , z 
n n n 

The '^^iV^ coordinates of each point specify its location in the x,y plane and the 
z. coordinate is interpreted as its height. Each x,y coordinate pair locates an 
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appropriate cell within the NX by NY grid into which the z coordinate value is ^ 
stored. Multiple z values mapped to a single cell are averaged together. Once 
the image space is complete, it is sent to an output routine which plots it along 
with titles and appropriate scaling information. 

The image space may either be plotted directly or may be subject to a two 
dimensional interpolation scheme which converts it into a set of interlocking planar 
regions. Interpolation may only be applied to data files which are organized in a 

special way; namely, the data points in a file must form a set of triangles in the 

I 

x,y plane. Consider the following region which is divided into four contiguous 




Each triangle is defined by three sets of x,y,z coordinates and the data file must 
be organized as follows: 



Note that each point occurs at least twice in the data file. Interpolation fits a 
triangular plane through the z coordinates, in each triangle. The points in the 
plane are Ax and Ay distance apart where Ax and Ay are specified by the user. 
Both Ax and Ay must be specified since the x and y axes may have radically different 
scales. This form of interpolation, or point-enrichment, is particularly suitable 
for displaying the solutions to finite element formulations. 

Input 

This write-up assumes that PL0T3D is already incorporated as a subroutine in 
an existing program which uses the format-free input package (Gales and Anderson 
1978; Anderson and Gales 1978). 

The user assignable variables in PL0T3D are XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX, 
XRICH, YRICH, DFAULT, XVIEW, YVIEW, ZVIEW, XC, YC, XSIZE, YSIZE, NX, NY, LBOX, 
LHIDE, PAGE, TITLE, and LOCTIT, and are described as follows: 

INPUT TABLE 



NAME 



TYPE 



RESTRICTIONS DESCRIPTION 



XMIN 
XMAX 
YMIN 
YMAX 
ZMIN 
ZMAX 




XMIN, XMAX, YMIN, YMAX, ZMIN, and ZMAX define a 
three-dimensional window which encloses all the 
data in the image 'space to be displayed. Data 
outside the window are not shown. If one or more 
of the following conditions hold: 

XMIN 2 XMAX, YMIN >_ YMAX, ZMIN >^ ZMAX 

the computer considers the limits to be unspecified 
by the user and computes new limits for the axis 
or axes in question which are sufficient to include 
all the data along that axis or axes in the image 
space. 
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NAME 



TYPE 



RESTRICTIONS 



DESCRIPTION 



XRICH 
YRICH 



Real 



DFAULT 



XVIEW 
YVIEW 
ZVIEW 



Real 



Real 



XC 
YC 



XSIZE 
YSIZE 



NX 
NY 

LBOX 



Real 



Real 



Integer 
Integer 



> 0 



> -10" 
± 10" 

I XVIEW I 

> XSTZE 
I YVIEW I 

> YSIZE 
I ZVIEW I 

> XSIZE 
I ZVIEW I 

> YSIZE 



0.5 £ XC £ 8 
0.5 < YC < 10.5 



XSIZE .1 

XC + XSIZE £ 8 

YSIZE .1 

YC + YSIZE £ 10.5 

2 < NX £ 30 
2 £ NY £ 30 

0, 1, 2, or 3 



XRICH and YRICH are the Ax and Ay increments 
used in two-dimensional interpolation (enrichment). 
If either is zero, no enrichment takes place. The 
user should note that the values of XRICH and 
YRICH should be coordinated not only with the 
data, but also with the size of the window set 
by XMIN, XMAX, YMIN, and YMAX. If either is too 
small, the computer will consume too much computer 
time, whereas large values of XRICH or YRICH will 
adversely affect the appearance of the plot. Note 
that interpolation should only be applied to data 
which are correctly organized on the binary data 
file. 

DFAULT is ''the default value assigned to all cells 
in the image space. DFAULT is usually set to 

zero. 

I 

The point of view in space, in inches, from which 
the plot is seen by the user. Normallyi XVIEW 
and YVIEW should be negative, indicating that 
the observer is behind the plot so that it 
appears in front of him, while ZVIEW should be 
positive, indicating that the observer is above 
the plot looking down. The user may have to 
experiment with different values for these view- 
points in order to obtain the desired view of the 
plot. 

The location on a page of the lower left corner of 
a box which encloses the plot. The distances are 
in inches from the lower left corner of the page. 

The size of a box, in inches, which is to contain 
the plot. 



The number of grid cells in the image space along 
the X and y axes. 

JThe box control for subroutine PICTURE. This 
parameter controls the structure of the three- 
dimensional window, or box, which contains the 
plot. The options are: 



LBOX 


0: 


No box lines. 


LBOX = 


1: 


Surface and box lines. 


LBOX = 


2: 


Surface, box, and side bars. 


LBOX = 


3; 


Surface, box, side bars and 






labels. 



Normally, LBOX = 3. 
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NAME TYPE - RESTRICTIONS DES CRIPT ION 



LHIDE 


Integer 


0 


, 1 


, 2, -1, -2 


The hidden line control parameter for subroutine' 
PICTURE. The options are: 

LHIDE = 0: No hidden lines removed, 
LHIDE = 1: Hidden lines of plot but 

LHIDE = 2: All hidden lines are removed • 
LHIDE < 0: Visible portions of the under- 
side are also plotted. 

Normally, LHIDE =2. 


PAGE 


Logical 


T 


or 


F 


If PAGE = T (true), then the current page is 
skipped and the current plot is written on the 
next page. If PAGE = F (false), the current 
plot is written on the current page. 

If TITLE = T (true), then the current plot 
consists of plot titles only, with no plot. 
If TITLE = F (false), then both plot and plot 
titles are written. Note that in the former 
case, the entire aii^a dpfinpfl hv y^T?^ v<5T7p 
is available for plot titles (or any other 
text), whereas in the latter case, the plot 
titles are either squeezed in near the top of 
the area defined by XSIZE, YSIZE, or just above 
it (see LOCTIT). 


TITLE 


Logical 


T 


or 


F 


LOCTIT 


Logical 


T 


or 


F 


If LOCTIT is T (true), then the plot titles 
will be contained wholly within the region 
defined by XC, YC, XSIZE, and YSIZE. If 
LOCTIT is F (False), the plot titles are placed 
above and outside this region. 



Output 

The output for PL0T3D consists of one or more plots per page. Each plot 
normally contains up to four lines of annotation near, or above, the top of the 
plot, along with x, y, and z axis labels.* 



Restrictions 



The two-dimensional interpolation function should only be used on data which 
are correctly organized on the binary file of x, y, z coordinates. 
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Error Messages 

PL0T3D issues three types of fatal error messages: input parameter errors, 
errors due. to zero width windows, and errors arising from enrichment of faulty 
data, in addition to warnings when z axis values lie outside the range defined 
by ZMIN, ZMAX. 

I 

The first type of errors is of the form: 

ERROR NO. X IN SUBROUTINE PLOT 3D 

^ yy*..y OUT OF RANGE 
yy . . . y = dd . . . d 

where x is 1 through 6, yy...y is the name of the variable, and dd...d is its 
value. The second type is of the form; 

ERROR NO. X IN SUBROUTINE PL0T3D 

COMPUTED a-axis IS ZERO WIDTH 
AT a = dd...a 

where x is 7, 8, or 9, a is X, Y, or Z and dd...d is the x, y, or z axis value. 
The third type is of the form: 

ERROR NO. 10 IN SUBROUTINE PL0T3D- 

TRIANGULAR REGION IS MALFORMED 
ITS POINTS ARE 

(x^,y^,z^), {yi^,y^,z^), ^-^yVy^^) 

ERROR NO. 11 IN SUBROUTINE PLOT 3D 

END OF FILE ENCOUNTERED BEFORE 
A TRIANGLE IS COMPLETE 
The warning messages are of the form: 

WARNING Z VALUES OUT OF RANGE 

n Z VALUES LESS " THAN z^ 
m Z VALUES GREATER THAN z^ 
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SMALLEST Z VALUE = 
LARGEST Z VALUE = 



COMPUTATION CONTINUES 

where and are ZMIN and ZMAX, respectively, n and m are the number of z 

axis values less than ZMIN and greater than ZMAX, in the image space, and x^ 

and X2 are t-he smallest and largest z values encountered. 

Errors 1 through 6 occur if the input parameters have improper values, 

errors 7 through 9 occur if the user is letting PL0T3D determine its own window 
size (by setting XMIN > XMAX and/or YMIN > YMAX and/or ZMIN > ZMAX) and all x 
coordinates are equal, or all y coordinates are equal, or all z coordinates 
are equal (for example, if only one point occurs in the image space). Error 
10 occurs if the three vertex points of a triangle form a single line, and 
error 11 occurs if the last triangle possessed only one or two vertex points. 
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Sample Run 

The annotated listing on the next few pages illustrates the control and 
input data cards for a sample run, along with the associated output. The output 
consists of a set of plots and annotation on one page which show the effects of 
various plot options applied to a single file of x, y, z coordinates. 



XPL3D#CM50000,T35f P2, PLTTBD TFST 

ACCCUNTf XXXXXXXXfXXXX XX. 

COMMFNT. 

COMMENT. ♦♦♦*♦***♦♦♦♦♦ 

COMMENT.* THE ABDVF CARDS IDErTlFY THE JOR^ SPECIFY THF MFMHRY « 

COMMENT.* REQUIREMENTS (50000 OCTAD^ ESTIMA^TE THE CENTRAL PPnc?=^^rP * 

COMMENT.* TIME (3! SECONDS)^ AND SPECIFY THE USERS ACCHUMT * 

COMMENT. *********** ******♦******♦**♦♦♦****♦♦♦♦♦♦♦♦****)>:♦♦♦♦♦♦%♦♦♦ 

COMMENT. 

MNF/E'Of R«7, J. 

COMMENT. 

COMMENT.************* *******♦♦*♦*♦*♦♦ 

COMMENT.* THE ABOVE CARD CALLS THE MINNESOTA FORTRAN fP-^PTlFP tIt t 
COMMENT.* COMPILE THE EXECUTION PROGRAM FOP »L0T3n ♦ 
COMMENT. *****♦***♦**********************♦*♦**♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦*♦*♦♦ 
COMMENT. 

ATTACH, BPL3DfID«BPL3D . 
COMMENT. 

COMMENT. ***************************** ♦******««***««*«*«*««*******4*4**j** 

COMMENT.* THE ABOVE CARD ATTACHES THF PLOTTING ROUTINE BINAPY FrPK * 

COMf^ENT. ************* *******♦♦*********♦*♦♦♦*♦*♦♦♦****♦♦**♦♦♦♦♦♦♦♦♦♦*♦♦♦ 
COMMENT. I 
ATTACH, RPF, ID«BFF. 
COMMENT. 

COMMENT. ************* ****«**********************iCs* ♦*♦♦♦♦♦♦♦*♦♦♦♦♦♦♦ 
COMMENT.* THE ABOVE CARO ATTACHES THE FRFF-FQRMAT INPUT PHUTINF^ IN * 
•CC^*MENT.* BINARY FORM. * 
C OM MENT. *********** *********************************** ♦♦♦♦♦♦♦♦♦♦♦it ♦♦♦♦♦♦ 
COMMENT. 
ATTACH, GPAFTN. 
L IBRARYf &RAFTN . 
COMMENT. 

COMMENT. ************* *************************** 

COMMENT.* THE ABCVF CARDS ATTACH THE LIBRARY i* 

COMMENT.* ROUTINES FOR PL3D AND DESIGNATE THAT * 

COMMENT.* FILE AS THE CURRENT LIBRARY. * 

COMMENT. *********** ***************************** 

COMMENT. 

LOADfBFF. 

L0A0>BPL3P. 

LOAD, LGJ. 

EXECUTF/XPL3D. 

COMMENT. 

COMMENT. ******************************************** 

COMMENT.* THE ABOVE CARDS LOAD THF EXECUTION, INPUT An:P PLOT PPHTINf^S * 

COMMENT.* AND CAUSE CONTROL TO BE PASSED TO XPL^O FOR FXFCUTI'^N * 

COMMENT.**************************************************************** 

CATAL0G^TAPE99^RP«5. 

COMMENT. 

COMMENT.**************************************** 
COMMENT.* THE A80VP CARD SAVES THF PLOTTING * 
COMMENT.* TAPE,-TAPrcJ9-, SO THAT THE PLOTS MAY * 
COMMENT.* Bb PREVIEWED BEFORE BEING SENT TO * 
COMMENT.* THE PLOT QUEUE. * 
COMMENT ***************************** ************ 
COMMENT. 

COMMENT. ***************************************************** *********** 
COMMENT.* THE BELOW CARDS APE THE EXECUTION PROGRAM XPL^n * 
COMMENT.************* **********'^******'»********************************* 
COMMENT. A o 
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♦ EOR 

PPCGPAM GGFS HEPE 

♦ EOR 
/* 

/♦ INITIAL PLDT PAOflMFTERS »/ 
/♦ 

XMIN - l.Of )(MAX » 5.0, YMIN ■ 1.0, YMAX • A.O, 

ZMIN « CO, ZMAX « 15.0, XRICH ■ 0.05» YRICH ■ O.Cr, PPAULT ■ C.C, 
XVIEW ■ 5.0, YVIFW ■ 13.22P> NX • 20, NY ■ 20, 
7VIEW ■ 30.0, 

LBDX » 3, LHIDF » ? 1. 
/* 

/* PARAf^ETERS FCP PLOT 1 */ 
/* 

XC ■ 1.5, YC ■ 8.0, KSIZF « 2.0, YSIZF - ?.C, 
TITLE • .F., LOCTTT « .F. $ 

/* 

/* PARAMETERS FQR PLOT 2 */ 
/* 

XC ■ 5.0, LCCTIT - .T. $ 

/* 

/* PARAMETERS F0» PLDT 3 */ 
/* 

XC ■ 3.0, YC ■ 3.5, XSI7E " 3.0, VSIZE - 3.0, Lf^CTTT • .F. f 

/* 

/* PAPAMtTEPS FOR PLCT <* * / 
I* 

XC • 3.0, YC ■ 1.5, XSIZF ■ 5.0, YSIZE ■ 1.0, 
TITLE - .T. % 

*EOR 

♦ EOF 
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